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SEI  Serpent  Application  Developer’s  Guide 


1.  Introduction 


Serpent  is  a  User  litterface  Management  System  (UIMS)  that  supports  the  development  and 
execution  of  a  user  interface  of  a  software  system.  Serpent  supports  incremental  devei- 
cprnwt  of  the  i^er  lhterf^  prototyping  phase  through  production  to  maintenance 

or  su^a^^  engineering.  Smpent  encourages  a  separation  of  functionality  between  the 
user  interface  portion  of  ^picadon  and  the  functional  portion  of  an  application.  Serpent 
is  also  easily  extended  to  ^port  addittdhal  input/output  technologies. 


This  Appife^tm  Dev^oper’s  Guide  describes  how  to  develop  applications  using  Serpent. 
q  The  contwts  of  this  giride  assume  that  you  have  read  and  understood  the  concepts  de- 
scribed  irr*An  Introductiori  to  assumes  that  you  are  experienced  with  using 

Parts 

This  guide’s  major  parts  are: 

•  Overview:  The  overview  part  of  ^  pro^des  a  general  description  of 
the  role  of  an  appUcaSw)  in  a  sr^ware  system  dev^oped  using  Serpent  It  also 
describes  a  concef^ua^  hamswotk  for  appiicaim  development. 

•  C  Language  Application  Davofepment:;  sections  in  this  part  address 

the  needs  of  C  language  appteafkm  cfovtiopers.  The  first  section  describes 
how  to  develop  an  application  using  Ssnpent  in  the  C  programming  language. 

The  second  section  contains  a  con^detei  sat  of  descriptions  d  ait  the  constants, 
types,  and  routines  available  to  theC  language  Serpent  appScattfon  developer. 

•  Ada  Language  Application  Dovak^mient:  The  two  sediois  in  fois  part  ad¬ 
dress  the  needs  of  Ada  language  ^>plication  cteveh^dorsi  The  fird  section  de¬ 
scribes  how  to  develop  an  applic^on  using  Smpent  in  the  Ada  programming 
language.  The  second  section  contsuns  a  cmpplste  sat  of  descripticms  d  ail  the 
constarrts,  types,  and  routines  avediabte  to  tile  Ada  lan^jage  Serperit^^^ 

tion  developer. 


•  Application  and  Dialogue  Testing  The  two  sections  in  tftis  part  of  this 
describe  an  approach  for  testing  the  application  and  dialogue  portions  of  a  soft¬ 
ware  system  developed  using  Serpeni  independent  of  the  implementation  larw 
guage  selected.  The  first  section  describes  the  task  steps  involved  in  testing 
while  the  second  section  describes  commands  available  to  the  application  m 
dialogue  tester. 

The  glossary  provides  definitions  and  explanations  of  ternis  that  are  used  fo  tills  guide. 
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2.  Overview 


A  main  9oat  of  Setpent  is  to  encourage  the  separation  of  a  software  system  into  an  appli- 
o^on  portion  and  an  user  interface  portion  in  order  to  provide  the  application  developer  with 
vmpfBserrtation  indepeddmt  interface.  The  application  portion  consists  of  those  components 
of  a  software  system  implement  the  "core”  application  functionality  of  a  system.  The 
user  intorface  porttoh  ccmsiste  of  those  components  that  implement  an  end-user  dialogue.  A 
idiaiogue  is  a  sped^ication  of  the  presentation  of  application  information  and  end-user  inter¬ 
actions. 

During  the  design  stage,  tiie  systmn  designer  decides  which  functions  belong  in  the  appli¬ 
cation  component  arKi  whb^  belong  in  the  user  interface  component  of  the  system. 

2.1 .  The  Serpent  Architecture 

Serpent  is  Implemented  udng  a  standard  U1MS  architecture.  This  architecture  (see  figure 
2-1)  consists  of  three  major  die  presentation  layer,  the  dialogue  layer,  and  the 

application  layer.  The  three  (tifldrent  layers  of  the  standard  architecture  are  viewed  as  pro¬ 
viding  differing  levels  of  endnjser  feedback. 


Rgure2-1:  Serpent  Architecture 
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The  presentatiort  ii^er  consists  of  various  input/output  technologies  which  have  been  incor¬ 
porated  into  Serpfflft  input/output  technologies  are  existing  hardware/software  systems  that 
perform  someievet  of  gemrralized  interaction  with  the  end-user.  Serpent  is  being  distributed 
with  an  Irtterface  to  the  X  Window  System,  version  1 1 .  Other  input/output  technologies  can 
be  trrtegrated  with  Serpertt.  See  the  Guide  to  Adding  Technoiogies  for  a  discussion  of  how 
^8  can  be  accomplished. 

Ore  way  of  viewing  ttei  three  levels  of  the  architecture  is  the  level  of  functionality  provided 
In'  user  input  The  pr^entation  layer  is  responsible  for  lexical  functionality,  the  dialogue 
lav«M(}  lE}f  syntactic  fi»tctionaiity,  and  £he  application  layer  for  semantic  functionality.  In  terms 
of  a  mmit  examf^,  the  presentation Jay^  has  responsibility  for  determining  which  menu 
item  was  selected  and  for  presenting  teedback  which  indicates  which  choice  is  currently 
selected.  The  dlalpgue^  respon^blllty  for  deciding  whether  another  menu  is 

presented  and  presenting  it  or  whether  the  cNrice  requires  application  action.  The  appli¬ 
cation  layer  is  responsfote  for  Implementing  the  command  implied  by  the  menu  selection. 

The  end-user  interfoce  for  a  software  sy^m  Is  specified  formally  as  a  diaiogue.  The  dia¬ 
logue  is  executed  by  the  diaiospmmanagmaii  runtime  in  order  to  provide  a  end-user  inter¬ 
face  for  a  software  system.  Hie  diaiogue  specifies  both  the  presentation  of  application  infor¬ 
mation  and  end-user  interactions^  The  Serpent  dialogue  specification  language  (SLANG) 
allows  dialogues  to  be  aibltaui^  complex. 

The  application  provides  the  functional  portion  of  tiie  software  system  in  a  presentation  inde¬ 
pendent  manner,  it  may  be  developed  in  0.  Ma,  or  otiie»‘  |»T>gramming  languages.  The 
application  may  be  either  a  functiorsif  slnsifotion  for  prcftotyping  purposes  or  the  actual  appli¬ 
cation  in  a  delivered  system.  The  actiorfo  of  the  appHcalfon  layer  are  based  on  knowledge 
of  the  specific  problem  domain. 

2.2.  Shared  Database 

Serpent  provides  an  active  database  mods||;lor  specifying  tiie  user  interface  portion  of  a 
system.  In  an  active  database,  muitipie  processes  am  atiowed  to  update  a  database. 

Changes  to  the  database  are  then  propagated  to  earftt  iser  of  die  database.  Titis  active 
database  model  is  implemented  in  Serpent  by  a  shared  database  that  logically  eetists  be¬ 
tween  the  application  and  I/O  technologies.  The  application  can  add;  modify,  c^iyt  or 
remove  data  from  the  shared  database.  Information  provided  to  Serpeht  by  the  appHcation 
is  available  for  presentation  to  the  end-user.  The  application  has  no  knowledge  of  the  pres¬ 
entation  media  or  user  interface  styles  used  to  present  this  information. 

Information  in  the  shared  database  rray  be  updated  by  either  the  application  or  i/O  fechnoi- 
ogies.  Figure  2-2  illustrates  the  use  of  the  shared  database  in  Serpent  ] 

Serpent  allows  the  specification  of  dependencies  between  elements  in  tire  sfoared  database 
in  the  diaiogue.  These  dependencies  define  a  mapping  between  appfication  data,  presen¬ 
tation  objects  and  end-user  input.  The  diaiogue  manager  enforces  these  dependencies  by 
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Figure  2-2:  Shared  Database 

operating  on  the  infonn^on  stored  in  the  shared  datebase  untii  the  dependencies  are  met 
Changes  are  then  propagated  to  either  the  af^Scatkm  the  i/0  technologies  as  appro¬ 
priate.  See  the.  SLANG  Reference  CkAde^r  a  ^r^r  discussion. 

The  type  ?nd  structure  of  litfomnnaHon  that  can  be  ms^nteined  in  the  shared  database  is  de¬ 
fined  externally  in  a  shared  data  de/fnflfoefiie.  Ttite  corresponds  to  the  database  concept  of 
schemas.  A  shared  data  definition  file  is  reqtdred  each  application. 

A  shared  data  definition  file  consists  of  b<^h  segregate  and  scalar  dala  structures.  Top-level 
data  structures  become  shared  data  efmrmits  that  may  be  instantiafed  at  rentime.  Nested 
data  structures  become  components  th^  are  considered  part  of  the  ^red  data  element. 
Serpent  does  not  allow  nesting  of  records. 

it  is  possible  to  define  multiple  instances  of  a  ^ngle  shared  data  element  ^ared  data 
elements  are  instantiated  by  specifying  tfie  elonent  name.  Each  shared  data  fnstance  is 
identified  by  a  unique  ID.  IDs  must  be  maintained  by  the  applicatiort  to  identify  Shared  data 
instances  when  multiple  instances  of  a  single  shared  data  element  exist.  Figure  2-3  pro¬ 
vides  an  illustration  of  shared  data  instantiation. 

Serpent  supports  both  a  synchronous  and  asynchronous  system  model.  This  Is  necessary 
since  an  application  often  needs  to  satisfy  real-time  constraints  and  cannot necessarily  af¬ 
ford  to  wait  for  end-user  input  This  introduces  a  situation  where  mui^sfe  proc^ses,  which 
are  using  the  shared  database,  may  access  or  modify  the  database  continently.  This  con¬ 
current  access  of  the  shared  database  may  result  in  a  situation  where  the  integrity  of  the 
database  is  corrupted. 
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SharBit  data  record  Instantiation  Shared  data  Instances 


FIgura  2*3:  glared  Data  Instantiation 

This  problem  is  solved  in  Seipent  through  the  use  of  database  concunency  control  tech¬ 
niques.  Updates  to  the  Seipent  shared  database  are  pac^ged  in  transactions.  Trans¬ 
actions  are  collections  of  t^dates  to  the  shared  database  diet  am  logically  processed  at  one 
time.  Transactions  can  be  started,  cotmMBKl,  or  rolled  bac^  Committing  a  transaction 
causes  the  updates  to  be  made  to  the  shared  database.  RolSng  back  a  transaction  causes 
termination  of  the  transaction.  AtransacScm  which  is  «^i1sd  but  not  yet  either  committed  or 
rolled  back  is  said  to  be  open.  TTiere  may  be  severai  tCEunsactions  open  at  the  same  time. 

2.3.  Application  Development 

There  are  three  major  tasks  which  need  to  be  performed  devetoping  an  appiication  for 
Serpent; 

1 .  Define  ...hared  data 

2.  Add  information  to  shared  data. 


3.  Retrieve  information  from  shared  data 

To  perform  each  of  the  preceding  tasks,  there  are  severai  steps  you  need  to  complete.  The 
first  task  is  completely  independently  of  the  language  in  which  the  application  was  d^ei- 
oped.  The  last  two  tasks  are  also  both  language  independent,  but  how  you  specify  toem 
depends  on  the  programming  language  you  chose  for  application  development  Currently 
Serpent  supports  two  different  language  interfaces,  C  and  Ada  Therefore*  the  two  parts 
that  follow  specify  and  illustrate  how  to  develop  an  application  in  the  G  and  Ada  program¬ 
ming  languages,  respectively. 
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2.4.  Application  and  User  Interface  Testing 


The  iQcord/playbadc  feature  of  Serpent  allows  you  to  record  transactions  between  the  appli¬ 
cation  smd  dialogue  manager,  or  between  the  dialogue  manager  and  the  various  technol¬ 


ogies^  These  transactkms  may  then  be  played  back  at  a  later  time.  This  is  useful  in  per¬ 
forming  regression  and/hr  stress  testing  of  the  application,  dialogue  or  technologies. 


There  are  two  ma|PI’  tai^  that  need  to  be  perfonned  when  using  the  record/playback  fea¬ 
ture  of  Serpent  fcii  te^ng  the  application  or  user  internee: 

1.  Reeorcing  shared  database  transactions. 

2.  Testing  the  appiicatton  or  interface. 


To  perform  each  of  the  preceding  tasks,  hiere  are  several  steps  you  need  to  complete.  The 
specification  of  steps  Irt  the  first  task  is  dependent  on  the  programming  language  selected 
for  appliceiion  development  Therefore^  a  description  of  the  steps  involved  in  recording 
shared  d^xtose  transactors  Is  inclucOl  In  both  the  C  language  and  Ada  language  appli¬ 
cation  development  parts  of  this  guide. 


The  execution  of  the  steps  Irr  the  second  task  are  performed  independently  of  the  language 
in  which  the  appiiC£dlof:|  was  developed.  These  tasks  are  described  in  the  Application  and 
Dialogue  part  of  this  gt^e. 


2.5.  Sensor  Site  Status  l^mple 

The  sensor  site  status  (SSS)  application  is  an  exan^le  of  an  application  developed  using 
Serpent.  Rgure  2-4  is  an  illustration  tire  *s(:^der  chart"  display  which  is  one  possible  end- 
user  interface  for  the  application. 

The  sensor  site  status  application  is  adapted  from  a  command  and  comroi  application.  The 
purpose  of  the  application  is  to  monitor  »rd  display  the  stahis  various  sensor  sites  and 
their  associated  communications  lines  to  the  two  emr^etirm  centers. 

The  columns  of  rectangular  boxes  on  the  right  and  left  sides  of  the  spider  chart  display  (for 
example,  GS1,  GS2)  represent  sensor  sites.  The  circles  in  the  middle  of  the  display  repre¬ 
sent  the  correlation  centers  that  collect  information  from  the  sensors.  Each  sensor  ^  com¬ 
municates  with  both  correlation  centers;  this  is  represented  by  the  duplication  of  sensor  site 
boxes  on  both  the  right  and  left  sides  of  the  display.  The  lines  present  the  communk:2ftion 
lines  between  the  sensor  sites  and  the  correlation  centers. 

An  operator  may  display  detailed  information  concerning  a  sensor  site  by  selecting  a  sensrM* 
site  box  corresponding  to  that  sensor.  This  causes  a  detailed  window  to  appesu'  displaying 
information  concerning  the  status  of  the  sensor,  the  date  and  time  of  the  last  message,  the 
reason  for  outage  (RFO)  and  the  estimate  time  to  returned  opwatiwi  (ETRO).  These  fields 
may  be  modified  by  the  operator.  Sensors  may  have  one  of  three  status:  green,  yellow  and 
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red.  For  sensonA^cti  are  not  fully  operational  (i.e.  status  is  green)  the  ETRO  is  displayed 
to  the  outside  of  tfe  sensor  site  box.  ETROSs  are  also  displayed  over  communication  lines 
that  are  ncft  fuRy  operationai. 

ITtrougiKXit  this  guide,  a  leteience  to  the  sensor  site  status  application  implies  a  reference 
to  ^  example. 
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3.  C  Language  Application  Development 

This  part  includes  two  sections: 

•  How  to  Devekjp  an  Application  in  C:  A  step  by  step  specification  of  the  tasks 
involved  in  doi^aic^ng  a  Serpent  application  in  the  C  programming  language. 

•  Serpent  C  Lan^jage  Interface  Reference:  A  detailed  description  of  the  types, 
constants  said  routines  available  for  developing  Serpent  applications  in  tfw  C 
programiryr^  language. 

3.1.  How  to  Develop  an  Application  in  C 

The  main  tasks  fcu'  davekping  an  appRcabon  for  Serpent  require  that  you  define  the  shared 
data,  add  information  to  ^red  data,  artd  retrieve  information  from  shared  data.  There  are 
also  two  SKlcfidonal  tasks  w^ich  may  ap|;^iecb  recording  and  checking  status.  Each  of  these 
tasks  is  d6scfft>ed  in  the  suteections  thaft  Mtow. 

3.1.1.  Task  1 :  Defining  ttie  Stared  Data 

Defining  shared  data  iim^ves  two  steps: 

1 .  Create  the  stared  data  definition  file. 

2.  Run  the  created  file  through  the  SADDLE  procesaar. 

The  following  is  a  brief  descriptton  of  each  of  these  two  steps.  The  SEI  Serpent  SADDLE 
User's  Guide  contains  a  more  conplet&  descripticm  of  bcAh  these  steps. 

Step  1:  Create  the  shared  data  defhdtbm  ^Mte  shared  data  definition  file  defines  the 
type  and  stnjcture  of  application  information  datmay  be  maintained  by  the  Serpent  shared 
database.  The  shared  data  definition  is  defied  in  an  external  ASCii  tile  in  SADDLE. 

Rgure  3-1  is  a  example  of  a  shared  data  ctofinition  file  sensor  ^te  status  application. 
The  content  of  the  shared  data  definitirm  file  is  independent  of  the  implementation  language 
used. 

The  file  shown  in  Rgure  3-1  contains  definitions  lor  the  data  shsued  between  Ihna  application 
and  the  dialogue  for  the  sensor  site  status  application.  The  tfloee  records  define  tile  type 
and  structure  of  the  sensor,  correlation  center,  and  cornrnunicaticm  line  application  qtl^ects. 
Note  that  these  records  only  contain  information  to  define  the  actual  objects;  they  do  not 
specify  how  the  information  is  presented  to  the  end  user. 

Step  2:  Run  the  creeM  file  through  the  SADDLE  processor.  Once  the  shared  data  has 
been  defined,  you  can  mn  the  file  through  the  SADDLE  processor  to  genersto  a  C  language 
header  file.  You  then  include  this  header  file  with  your  C  application  in  order  to  declare  local 
variables  of  the  shared  data  types.  This  allows  you  to  directly  martipulats  shared  data  struc¬ 
tures  in  C.  The  C  header  file  generated  by  running  the  shared  data  definition  file  shown  in 
Rgure  3-1  through  the  SADDLE  processor  is  illustrated  in  Rgure  3-2. 
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••nsor__«i.1;«r_sta'tus :  sh&rttd  data 

mmamoxi  ::'-:raeord,: 

:  atcsag  [  3  ] ; 
atatua :  intagaxr; 
aita : atxiag [ 50} ; 
laat_Baa  aaga ;  atxing [ 8 ] ; 
r£o :  abring  [50| 
atro : atxiag}8} t 
and  racosd; 

caacralaitiyofti^^eantar  :rasord 
naiMk  t  atxiag  [  3  }  ; 
atatua :  int^raa; 
and  raoord; 

coeaninieatiottHLina :  raeor  d 
£raia_:MMor :  id  o£  aaaaox; 
to^cc^id  of  corralation^cantag; 
atro : atriag [ 8] ; 
abatna : iabagar ; 
and  xacord; 

and  ahaxad  datar 

t^ure  3>1 :  A  shfood  cteda  fUe 

idafina  MXZL^BOX  "aaa^jaailboaE'* 
idafina  XLL^rxu  "aaaTilX” 

bypdaf  atxneb  { 
char  aita^abbr[4] 
inb  atabna; 
char  aita[51]; 
char  laab_inaaaaga  [  9] ; 
char  r£o[51] ; 
char  abro[9]; 

}  aanaor; 

bypadaf  atrueb  ( 
char  aaiiia[4]; 
inb  ababaa; 

)  corralabion__caabar; 
bypadaf  abrucb  { 

id_bypa  froa__aanaor;  /*ZX>  of  aanaor  */ 

id_bypa  bo__cc;  /*ZD  of  corralabion^canbar]  */ 

char  abro[9]; 
inb  ababna; 

}  com Mnicabion_lina ; 

Figure  3-2:  C  language  header  file 
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In  Figure  the  first  two  lines  in  the  file  define  two  well-known  constants:  MXZLjaox  and 
ZLLjrzxx.  ITtese  <»nstants  are  used  in  task  2  to  initialize  Serpent.  The  three  typ«de£s 
correspond:^  the  rearms  defined  within  the  shared  data  definition  file. 


3»1.2.  Task  2:  Addktg  Information  to  the  Shared  Database. 

Once  you  have  defined  ^e  application  shared  data,  you  can  begin  to  develop  the  appli¬ 
cation.  The  code  segment  from  the  sensor  site  status  application  in  Rgure  3-3  illustrates 
the  basic  operatiorfisidr  adding  information  to  the  shared  database. 

finclude  ^mmxpmat.V  /*  serpent  interface  definition  */ 
#iii^Qda  ^"ssa.h"  /*  application  data  structures  */ 

idef  ine  SRXES^SXSaroS  0 
idefine  1 

idef  ine  JOBQ^  2 

aaiaO 

{ 

transaction_type  transaction;  /*  transaction  handle  */ 

correlation^cester  <flBO>oft;  /*  correlation  centers  */ 

serpent_iait;plU^^  ZXJ._rXLX) ; 

strcpy  (oft  .name,  ”On”) ; 

oft^status  >  ORSZS^SlSSaSr 

transaction  «v^:Stm3Sh;;tsaasaOtion;(:}::f;::::::''::^ 

omc_id  «  add_shared^dat«.( 
transaction , 

"correlation  center", 

MULL,  ” 

Seme 

oft_id  ■>  add_shared_data  ( 
transaction , 

"correlation_center " , 

NOIL, 

Soft 

)  ; 

ooBBDit_transaction  (transaction) ; 

serpent^cleanup ( ) ; 

return; 

> 

Rgure  3-3:  Basic  calls  for  adding  information  to  the  Glared  database 
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Preliminary  Task  Steps 

In  preparation  the  task  of  adding  information,  you  need  to  complete  two  preliminary 
steps: 

U  Incfude  header  ffieSr 

2.  Define  locaJ  variaUes., 

Step  PI:  Include  heedetlBies.  include  the  two  header  files,  as  shown  in  Rgure  3-3.  The 
these  two  filel^;i$  Qi|fied  serpent h  and  contains  the  definition  for  the  Serpent  external 
inteiface.  Ittls  rmsi  be  included  first  since  it  contains  type  definitions  that  are  used  in  the 
second  ffi&  Tte  second  file  that  needs  lo  be  included  is  the  C  language  header  file  gener¬ 
ated  in  the  previous  step«  s^ien  you  mn  fiie  shared  data  definition  through  the  SADDLE 
processor.  This  file,  sn;h  in  the  example,  rtefines  the  structure  of  the  shared  data. 

Step  P2:  Detym  loeai  veHdUea.  The  next  prefiminary  step  is  to  define  the  required  local 
variables.  The  variable  defined  is  transacfion,  which  is  of  trmasaeti.on_typ«.  This 
variable  maintayns  the  handle  for  a:^»ated  treuisaction.  The  next  variables  to  be  defined  are 
oBo  and  oft,  both  of  which  are  type  oorr«lati.on_c«ntax.  These  variables  store 
local  instances  of  the  data  that  is  shared  across  the  interface  with  the  Serpent 

system.  The  type  definitkm:  oorr«latioa__caatar  stmcture  was  automatically 

generated  by  the  SADDLEprooessor  during  step  2  of  task  1« 

The  two  variables  that  fofiow,  emc_i.d  and  deste  die  ids  of  the  shared  data  in¬ 

stances  created  in  shared  da^  It  Is  necessary  for  the  apfriksation  to  .maintain  this  infor¬ 
mation,  since  it  is  the  only  way  to  otfn^ate  end-user  updates  with  local  application  infor¬ 
mation  when  multiple  instances  of  a  singta  sirered  dafa  etement  are  used. 

Main  Task  Steps 

The  main  task  of  adding  information  to  the  slMoed  database  involves  five  distinct  coding 
steps: 

1 .  Initialize  Serpent. 

2.  Start  a  transaction. 

3.  Add  shared  data  to  the  interface. 

4.  Commit  the  transaction. 

5.  Cleanup. 


Stsp  1:  Initialize  Serpent  Once  the  appropriate  variables  have  been  declared  It  is  possfi>le 
to  begin  describing  the  logic.  The  first  step  is  to  initiaiize  the  Serpent  system  using  the 
call  and  passing  the  iolcljiox  and  zij,_rzu  constants  generated  by  the 
SADDLE  processor  during  step  2  of  task  1 . 


Step  2:  Start  a  transaction.  Before  information  can  be  added  to  the  sfiiaued  database  it  is 


necessary  to  start  a  transaction.  Ail  additions  or  modifications  to  the  ^red  database  must 


be  performed  as  part  of  a  transaction. 
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step  3:  Adel  tnlormatlon  to  the  shared  database.  Once  a  transaction  has  been  started, 
you  can  beg^  to  add  information  to  the  shared  database  as  part  of  this  transaction. 

Stap  ^  Commit  fhe  iran  The  actual  change  to  shared  data  does  not  occur  until 

the  bansaction  is  cotmi^tted.  Up  to  this  point  it  is  also  possible  to  roll  back  the  transaction 
so  that  none  of  the  charges  to  shared  data  occur. 

Step  S:  Clean  sArpant^clttanv^  routine  must  be  invoked  before  exiting  the 

application.  It  Is  Iti^rtant  that  you  complete  this  step,  to  release  all  allocated  system 
fBsoumes. 

3.1.3.  Task  3:  Retrie^ng  infoiinatlon  from  the  Shared  Database 

Once  application  data  a^dsts  in  the  shared  database  it  may  be  presented  to  the  end-user 
using  one  or  more  of  bte  available  tec^oiogies.  The  end-user  may  in  turn  make  modifica¬ 
tions  to  thte  data.  These  trxxlifications  are  sent  back  to  the  application  to  be  updated  in  the 
applicatiOft*8  local  database.  It  is  ther^ie  necessary  for  the  application  to  retrieve  infor¬ 
mation  bac^  from  the  shared  database. 

The  Serpent  interface  provictes  both  synchronous  and  asynchronous  calls  for  getting  infor¬ 
mation  back  from  the  Stared  database.  The  following  code  segment  from  the  sensor  site 
status  application  \n  Rgure  3-4  illustrates  the  basic  calte:  required  to  synchronously  retrieve 
data  from  the  interface. 

/♦ 

Retrieve  iji£oTmetioa:f£eoai  ehered  detebese . 

*/ 

transeetioa  «  get_treasMctiOA(>;: 

id  >  get_firat_chenged_eileeietit  (trenseotioa)  ; 

while  (id  !-  null^id)  { 

shered_dete_eleBMnt  <■  g«t__£raaijJkeeht^le  (id^teble,  id) ; 
iaeoxpoeete_changes  (trenseotiott,  id,  ehexed__detejelenent) ; 

id  s  get_next  ehenged  eleoMnt  (transeetioa) ; 

) 

parge_traasaetioa (transaction) ; 

) 


ngure  3-4:  Basic  calls  required  to  retrieve  data  synchrorxHisiy 
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Task  Steps 

The  task  0^  from  the  shared  database  involves  three  distinct  coding 

steps: 

1.  Get  a  transaction, 

2.  Update  local  database, 

3.  Purge  transactirm. 

SkifM:  CM  a  The  fin^  step  in  retrieving  infbnnation  from  the  shared  data 

base  is  to  get  a  bcmsaction.  The:  routine  waits  until  a  transaction  is 

avaiiat^  smd  fit&n  returns  a  ^  this  transaction.  To  poll  for  a  new  transaction 

asynchronously,  it  is  possit^e  io  call  the  g*t__tr«nsaetion_nojimi.t  routine,  which  will 
return  not__«vailaba«  If  no  transaction  is  available. 

Step  2:  Update  tae^  daiabme.  Transacfons  can  be  thought  of  logically  as  a  list  of 
changed  elemertts.  The  ne)d  cai^  g«t._£ir«trehang«d_«laiBant,  returns  the  id  of  the 
first  changed  element  on  the  Rst  T)tis  id  can  ttmn  be  used  to  access  several  types  of  infor¬ 
mation  about  the  shared  data  elecrmr^ 

The  application  must  mainiGto  a  correlation  between  the  shared  data  ids  and  the  actual  data 
items  to  incorporate  changes  successfully  into  its  existing  local  data.  For  the  purposes  of 
this  example,  it  is  assumed;  that  this  database  is  malr^ihied  as  a  hashtable  indexed  by  the 
shared  data  element  id.  The  purpose  of  tite  wbBe  toq)  thw  is  to  incorporate  ail  of  the 
changes  into  this  local  database  or  ha^itaUe;.  A^pointer  to  the  shared  data  element  to  be. 
updated  is  retrieved  from  the  ha^’Aat^  u^ng  the  routine  and  pass¬ 

ing  id  as  an  index  into  the  hashtable.  The  iaoozpo«Kb«_ehaag«s  call  then  makes  the 
updates  to  the  local  description  of  the  shared  data  elements  and  whatever  changes  were 
made  by  the  dialogue. 

The  last  call  within  the  loop  gets  the  next  flanged  element  from  tfw  thtftoacdon.  The  loop 
repeats  until  a  iraiJ^d  is  returned. 

Step  3:  Purge  tranaaetlon.  After  the  loop  ends  the  baiisaction  can  be  purged  safely.  It  is 
you.  responsibility  to  ensure  that  transactions  aie  fairged»  since  call  releases  resources 
that  otherwise  could  run  out. 

3.2.  Recording  Shared  Database  Transactions 

There  are  two  major  tasks  that  need  to  be  performed  when  using  the  recorcyplayback  toa- 
ture  of  Serpent  for  testing  the  application  or  user  interfoce: 

1 .  Recording  shared  database  transactions. 

2.  Testing  the  application  or  user  interfs^. 

Since  the  steps  involved  in  the  second  task  can  be  performed  independently  of  the  imple 
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mentation  langiage  they  are  described  later  in  the  Application  and  Dialogue  Testing  part  of 
this  giida 

Before  t^ing  the  application  or  the  dialogue  however,  you  must  first  record  the  transactions 
you  would  like  to  use  In  testing.  Figure  3-5  illustrates  the  basic  operations  for  recording 
transactions. 

txanseetiott  'type  traneectxon; 


/* 

Start  raeordxag. 

*/ 

start  raeording("racordxag",  "test  data:  5.7.3"); 
/*  ~ 

Sand. -test  datav 

*/ 

transaction  «  start  transaction (} ; 


cooBBit^tranaaetion  (transaction) ; 

'  transaction  m  start  transact A  on ^ 


eoanit^transaetion  (transaction} 
transaction  •  start  tranaaotien  () ; 


eonsuLt  transaction  (tranMction) ; 

/* 

Stop  recording. 

*/ 

stop__recording() ; 


) 

ngure3*5:  Recording  transactions 

Task  Steps 

There  are  three  distinct  coding  steps  involved  in  recording  shared  database  transactions: 

1 .  Start  recording. 

2.  Send  transactions. 

3.  Stop  recording. 
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Step  1:  Staart  recording.  The  first  step  is  to  begin  recording  by  ceiling  the 
vtartjcttoordixkg  routine  specifying  both  the  name  of  the  file  in  which  to  save  the  record¬ 
ing  and  amessage  to  help  identify  the  file. 

Step  2;  Send  trenseeikms.  After  the  call  is  made  you  may  start  sending  transactions 
across  the  interface.  You  may  send  any  number  of  transactions  containing  any  type  or 
amount  of  data. 

Slepi3:  Stop  reeoreU^f.  Once  •‘b«rt_recorduig  has  been  called,  all  transactions  and 
associated  data  wiB  be  saved  out  to  tee  specified  file  until  the  stop^recording  routine  is 
invoked. 

3.2.1.  Checking  Stetus 

Each  routine  in  Serpent  sete  status  on  eadL  it  is  good  software  engineering  practice  to 
check  this  status  after  every  cafi  to  make  sure  teat  the  routine  has  executed  correctly,  and 
provide  appropdate  recovery  actioes  if  it  has  rtot.  Figure  3-6  shows  the  operations  that  Ser¬ 
pent  provides  fw  examining  the  status. 

txanMction  *  atart^tsaaMCtionO ; 

daring  s^arb^jbransaetion") ; 

return; 

)  ■  "If 

Rgure3-6;  Operatidns  for  exaurfirfing  tee  status 

The  first  of  these  status  calls  is  tee  getsjstmtus,  wttich  returns  an  enumeration  of  status 
codes.  Valid  status  that  each  routine  in  Serpent  ritey  return  are  defined  in  the  reference 
sections  of  this  developer's  guide.  Successfod  ^xeojdon  (or  "OK")  is  always  set  to  zero; 
hence,  it  is  possible  to  make  the  simple  bodean  comparison  shown  fo  Figure  3-6  for  bad 
status. 

The  print^s^n^us  routine  prints  out  a  userdefined  errormessage  and  the  currant  status. 
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3.3.  Serpent  C  Language  Interface 
3.3.1.  Types  and  Constants 

subsection  colons  the  type  and  constant  definitions  that  are  used  in  the  C  language 
iii^rface  to  the  SerpcKtt  system.  The  following  is  a  list  and  short  description  of  each  of  these 
types  and  constants:^  complete  description  immediately  follows: 

Type/Constant  Description 

haftmx  used  to  define  the  structure  of  a  shared  data  buffer 

defines  the  of  modification  made  for  an  element 

id_typs  used  to  unique^  identify  shared  data  elements 

defines  the  null  value  for  the  id_typ* 

an  enumeration  of  defined  Serpent  data  types 

txanMction_typ« 

~  used  to  define  transac^n  handles 

nndefxnad  vmln«s 

Con^ants  corresponding  to  undefined  values  for  all  supported  types 
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TYPE 


OESCraPTiON 


DERNITICJN 


TTie  hatfms  type  is  used  to  define  the  staicture  of  a  buffer  within 
shared  data. 


t^|^p«da£  struct  ( 
int  Isagth; 
csddr^t  body; 

}  bo££sr; 


Components  isngtb 
body 


Length  of  the  buffer  in  bytes. 
Address  of  die  aotciai  buffer  data. 
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change_type 


D^riphon 


DERNITION 


Jtie  changejype  defines  the  type  of  modification  made  for  an  eiement. 


typmdmt  •nus  chang«_byp«  { 
Bo^chang*  -1, 

ezaata  «  0, 

aodiJS^  >  1, 

gat. 5. 

}  chuga^typa; 


Components 


no^changa 


oraata 

modify 


*  Ncrt  d'^tnged  or  tn^id  change. 

Remove  existfi^  shared  data  instance. 
Newly  cr«d»f  shared  data  instance. 

$  l^dified  shared  data  instance. 

:  Rik^  shared  data  instance. 

Gel  vafaie  for  existing  shared  data  instance. 
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TYPE 


ld_type 


DESCmPTiON  Thd  id  type  is  to  uniquely  identify  shared  data  elements. 


DERNITION  private  ; 
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Constant 


nutt  id 


DESCRifmoN  The  nulljd  cmstant  defines  the  null  value  for  the  id_type.  This  con¬ 
stant  can  be  used  to  test  for  null  id  values. 


definition  #d«£ia«  nttll_i.d  {iid_id_type) -1 
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TYPE 


serpentjdata_types 


11ie  serpent  data  types  type  is  an  enumeration  of  the  defined  Serpent 
datatypes. 


DESCffipnoN 


Dernition 


«nia&  dmtm^ypma  { 
■erp«inttjnttll_dat«^type  ■-!, 
•ezp«BbJboolean 
MmrpmBt^intmgmx  aOL, 
cexpent^real 
serp«nt^si:xiag  »3 , 
s«3ii|P«a£^^  >■4, 

Mogpeat^boffer  »€/ 
•eatgp4uati^iiada£xn«d  m? 

}  ••xpent^date^tjipM; 
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Descriptk)N  Variables  of  transactionjtype  are  used  to  define  transactions. 


Definition  privatte  toanaaetion__;typ«; 
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Constants 


undefined  values 


DESCRiFnON  The  following  constants  correspond  to  undefined  values  for  all  types 
^ported  by  Serpent  These  constants  can  be  used  to  test  for 
ndefined  Glared  data  components.  When  checking  for  an  undefined 
record  vs^e  it  Is  best  to  check  the  buffer  length  failed  for 
dHOBmaED  BOmERUBHSTH. 


DEFINITION  (boolean)  OxAAAAAAAA 

idafina  aiBMgaH»p|lCTCER  (int)  OxAAAAJUUUl 
fdafina  OBDKrX^^  (donbla)  OxXiUUUUUUUUUUUUUUk 

#da£iaa  dlBnDrziaBD^STRms  (string)  0xJUUUUUU)0 
fda^a  d!IDSriXED_BSCOBD  (eaddr^t)  OxAJUUUUUiX 
fdafine  T»IOXriXaED~ZD  (iid_ML^ype)  OxAAAAAAAX 
idafina  DnDXrXHKD^BOITBt^lJEiirarS  (int)-l 
idafina  nNDBTZinBDnEBITSirBOOf  (eaddr  t)OxMUUUUUUi 
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3.3.2.  Routines 

This  si4)sectiG»i  describes  the  routines  that  make  up  the  C  language  internee  to  Serpent. 
Th^eTQudnes  fafl  Into  the  following  categories: 

» initiaiization/desuitip 

•  serpentjnii 

•  serpei^lidMuiup 

•  Transaefon  processing 

*start_transaction 

•  commltjtcansactlon 

•  rollbaclc_tiaiisaction 
•getjiansacltort 

•  getjtransactlon^nojwait 

•  purge.transacdon 

•  Sending  and  relieving  data 

•  add_shaied_data 

•  put_shar9d_data 

•  remove_shared^data 

•  get_flrst_changBd_elBnrwnt 

•  get_next_changed_eleroerrt 

•  get_sharBd_data 

•  incorporate_changes 

•  create_changed_componentJist 

•  destroy_changed_componenUlst 

•  get_change_type 

•  getjelementjTame 

•  get_shared_datajype 


•  Record/piayback 

•  start.recording 

•  stop..rBCording 

•  Checking  Status 

•  get_status 

•  prirtt_status 
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Function 


add 

sliared  data 

DSSC»«PTiON 

Hie  add_aharodM«ta  routine  creates  an  instances  for  the  specified 
^red  data  els<r»nt  and  returns  a  unique  ID.  The  shared  data  in¬ 
stanced  m^ormay  not  be  initialized. 

Syntax 

i^type  add_aharod^defe*  ( 

/*  kratt«eetloa  :  la  teanaaetxon_typo  */ 

/*  alananfc^aaBM  :  ia  string  */ 

/*  eoagMMiit_;aaaMi  :  in  string  */ 

/*  data  X  in  eaddr  t  */ 

); 

Parameters 

transaotiott 

The  transacfion  fbrwNeh  this  opttafion  is  defined. 

•l«Banti__naaM 

The  name  of  the  shared  dida  el»nefit 

coaponont._xiai 

na  The  name  of  a  specific  oon^poneitt  to  be  initialized  arfththe  data  or  null  if 
the  data  corresponds  to  die  ertfre  element. 

dato 

data  or  null  pointer  If  nbPiliiEidized. 

Returns 

The  ID  of  the  newly  created  shared  data  instance. 

Status 

ok,  out^of^aMBory,  nnll^oT omont  ttmam,  ovorflow) 
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Routine 


coaimit  transaction 


OisCRtPTION 


fhe  oonait^txansaetion  procedure  is  used  to  commit  a  transaction 
to  the  sharacTdatabase. 


Syntax 


void  eoiBBiit_brsaMction  ( 

/*  txazisacti-oa:  in  transaction  typa  */ 

); 


Parameters  taransaiciion  Existing  transaction  ID. 


Status 


ok,  ont^ogjnsBiri ry ,  isvmlid_transactioa_handla 
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Function 


create_changed_componentJist 

iilf 

C^SCfUPHQN 

Tho  er«at«_j^kasig«d_caapoiMn't_liat  function  accepts  an  in* 
stance  id  as*a  parameter  and  creates  a  list  of  changed  component 
names. 

SYNTAX 

UfiT  ozMite^eh«ng<id^ooii^n«nt_lis^  ( 

/*  id:  in  id  type  *f 

); 

Parameters 

id  Existing  data  instance  id 

Returns 

The  list  of  xdiartged  (X>rr!fKmeni  names  associated  with  a  data  instance, 
orMOLLif  nom. 

Status 

ok,  iavnlid^id,  ont_^o£jBHBory,  •lflnMit^ao^^e_rocord 
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Procedure 


destrby_cHanged_componentJist 


Descrifuon  dastj:oy_jehang*d_coapoiiant_list  procedure  releases 

storage  associated  wite  a  cFanged  component  list. 


Syntax  deatcoy_ehang*d_ooapOMnt_lxst  ( 

/*  eoaponent  list  :  in  out  LIST  */ 

); 


Parameters  cfaatBgn^eoapon«nt_list 

UsTto  be  destroyed. 


Status  ok 
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Function 


get^hangejy  pe 

DESCRiPmiN 

The  g«t__ehan9tt£typ«  function  accepts  an  instance  id  as  a  parameter 
and  returns  the  associated  change  type. 

Syntax 

g«t_ehaiag«i_typ«  ( 

/*  iai^  :  in  id  type  */ 

Parameters 

id  Existing  shared  data  ID 

Returns 

Element  name  associated iidth  the  shsued  data  instance  ID. 

Status 

ok ,  invalid_chasg»^ti3rpe#i:;^^:^^  , 

invmlid_id 
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ge^lemehtLname 


Description 


the  g«tjgiaiiittnt_naatt  function  accepts  an  instance  id  as  a 
param^erand  returns  the  associated  eiement  name. 


Syntax 


jTfcriAg  ( 

/*  id  :  in  */ 


Parameters  id 


Existing  shared  data  iD. 


RETURNS 


Status 


Element  name  assodc^  shared  data  instance  ID 


ok,  in-vmlid_id 
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Function 


get_fflrst 

_changed_element 

DESCFUPnON 

Hie  qmt_£xrMW^jshmxigmdjtlmamnt  function  is  used  to  get  the  id  of 
the  first  char^ed^ment  on  a  transaction  list. 

Syntax 

id_jbyp«  g«t.^£lrst;^dhengttd_*l«in«nt  ( 

/*  ^rwMactlon  ^S!p«  :  in  trauxsnction  */ 

>; 

Parameters 

trananotiosi  Existing  transaction  ID 

RETURNS 

The  haridle  of  the  ^rst  changed  dement 

Status 

ok,  ittvmlid_tr«neaat:iox^handla ,  out_o£_jB«aoxy 
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Function 

get_next_changed_element 

Description 

The  g«t_^naaEt_^chang«d_*l«mMit  function  is  used  to  get  the  id  of  the 
next  chs^ed  Sement  on  a  transaction  list  or  return  null_id  if  the 
transaction  Bst  is  empty.  ~ 

Syntax 

xdjb^fp*  g«'b__n*xt,_jehang«d__el«iaent  ( 

/*^fcranaactioa  'tsfpe  :  in  transaction  */ 

); 

Parameters 

transaotion  Existing  transaction  ID 

A 

Returns 

The  handle  of  the  next  changed  element 

Status 

ok,  invalid_jtxaasacfeiMi_handla,  out^jofjnainory 

r 
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Function 


get^harecTjdata 


DE^lnypTiON  Hia  9ttt_sharMll^data  function  allocates  process  memory,  copies 
shared  data  into  process  memory  and  returns  a  pointer  to  the  data. 

Warning:  Record  corhpdrierits  rnay  not  have  been  spedfied  and,  therefore,  would 

not  corrtarn  valid  data 


SYNT ax  caddr^t  gafc^aharadLjiaba  ( 

/*  tranaaetioa  ;  iA  transaetion_bypa  */ 
/*  id  :  ia  id_jb]fpa  */ 

/*  conpooMit:  nama  :  in  string  */ 

); 


Parameters  txaasaetios  TrEtf^action  in  which  to  find  the  shared  data  id. 

id  Exisfing  shared  data  id. 

cooponant^nama  Narr»  of  coh^nent  for  which  to  retrieve  data  or 
~  entire  efemertt  if  NULL. 


RETURNS  A  pointer  to  changed  data 


Status  ok,  invalid__^id,  oat;_of_jiamory ,  ineoaiplata__raoord 
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Function 


get_shared_data_type 


DESCRIFnON 


The  9«tjBhared_data._typ«  function  is  used  to  get  the  type  associ- 
ated  with*a  sharecfdata  eiement. 


Syntax  s«Bp«n‘t__data__'tjpM  ge'b_sharad__data_type  ( 

/*  «l«aiant__naina:  in  string  */ 
f*  oomponant  nama:  in  strixxg  */ 


Parameters  aianaat_naiDa  The  name  of  the  shared  data  element 

oaB^nant__naaMi  The  name  Of  the  shared  data  component,  or  NULL 


Returns  The  type  of  the  shared  data  eiement  or  record  component. 


Status 
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Function 


gef^^tus 

Descfuftion 

The  function  returns  the  current  system  status. 

Syntax 

x«e^st«biu  ( ) ; 

Parameters 

None. 

returns 

The  cufient  status. 

Status 

Non* 
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Function 


gat^ransaction 


DESCRlPTiON 

The  gttt_jbr«asacti.oa  function  is  used  to  synchronously  retrieve  the 
id  for  theltext  completed  transaction. 

SYNTAX 

trattMetion_type  g«t__transae^io&() ; 

Parameters 

None. 

Returns 

Tlie  transaction  ID  for  a  completed  transaction 

Status 

ok,  ss!et4W^Of>fx»txon_£iidled 
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Function 


geTjransacflon_no_walt 


DESC^FTION  llie  gat__txan««dti.o&  function  is  used  to  asynchronousiy  retrieve  the 
fd  for  theTiext^CQA^teted  transaction. 


Syntax  <  teeaixasetion__typ«  ga!t_transac^ion_no_imi.t  ( ) ; 


Parameters  None. 


Returns  The  transaction  ID  for  a  completed  transcKition 


Status  ok^  syst«a|;;;ppwea±i»oa_£alled,  ttot^avaxlable 
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bic^iporate_changes 


Description 


Syntax 


Parameters 


Status 


The  iAcoxpsxa^Ajchangea  procedure  is  used  to  incorporate 
changes  into  locai  process  memory  without  destroying  unchanged  infer- 
matiCH). 


void  ijicozpora'ta^oliaxigoa  ( 
/*  id  :  ia  id^ibypa  */ 

/*  data  ;  t  */ 

); 


data 


Existing  shared  data  ID 

Reorder  to  deda  ¥dth  which  to  incorporate  changes. 


ok,  invalid_^id 
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Procedure 


priiit_status 


17)0  print^s-tatins  procedure  prints  out  a  user  defined  error  message 
the  curr^  st£^. 


C^scmpTioN 


Syntax 


voiid  prxn’t^sta.tvs  ( 

t*  ersox  mag  :  in  atring  */ 

); 


PARAMETERS  error 


User-defined  error  message. 


Status  iftone 
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l|;>tirge_transaction 


DESCRIPTION 


Syntax 


The  purge  tisnsaction  procedure  is  used  to  purge  a  received  transaction 
once  the  contents  of  the  transaction  have  been  examined  and  acted 
upon. 


void  purge^txattsaefeion  ( 

/*  -transaction  ;  in  transact ion^^typa  */ 


Parameters  traztsaetion  .Existing  transaction  ID. 


Status 


ok,  invalidJLdf  illagal^racaivar 
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Routine 


pul^^aredjdata 


||l||i| 

DSSCRtPTiON 

The  pat_ahar«d^dat«  call  is  used  to  put  information  into  shared  data. 

Syntax 

«9>id  put^aharadjdata  ( 

f*  txaaaae^ion  ::  iA  txanaaetion_typ«  */ 

/♦  id  I  ia  id_t3fp« 

/*  alamatit^nana  ;  ia  string  */ 

/*  oMWponsBt^anie :  ia  string  */ 

/*  data  ;  in  oaddr  t  */ 

) ; 

Parameters 

traasaotion  The  transaction  the  shared  data  should  be 

put 

id  Shared  data  ID^ 

alsBaat^aasw  The  name  of  the  ^red  data  element 

oooponant  jaaaa  The  name  the  shared  data  component, 
data  Shared  dsdet 

Status 

ok,  Tindafinad_sharad_data^ts^ai,  nall^jalaswat^nasM, 
invalided 
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Procedure 

• 

reiriove_sharecl_data 

• 

Description 

The  r«nov»jihar«d_data  procedure  is  used  to  remove  a  specified 
shared  data  instance  from  the  shared  database. 

• 

• 

Syntax 

voijd  x«nkOva_slkared_da'ta  ( 

/«  txansactlm  :  In  txmnaaetlon__typ«  */ 

/*  nlnmantjaaiaa  ;  in  string  */ 

/*  id:  ::  in  id  typa  */ 

); 

• 

Parameters 

transaction  Transaction  frcmt  which  to  remove  the  shared  data 

element 

alsBMBtjasBBa  Name  of  etonent  io  be  removed, 
id  Existing  shamf  data  ID. 

• 

Status 

ok,  out_of_iiiamory»  nnll_aloaBant__nMBar  invalid__id 

• 

• 

• 

''TrKTd'fT-iirc' 
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Procedure 

rotiback_transaction 


C^SCRiPTlON 

Ths  xoUbaek^tsansaetxon  procedure  is  used  to  abort  a  given 
transaction  andbeietB  the  associated  transaction  buffer. 

Syntax 

voiid  rollback_tr«Dcaetion  ( 

/*  tesAeaebion  :  in  transaction  typa  */ 

>; 

Parameters 

transaction  Existing  transaction  ID. 

Returns 

A  handle  to  a  newfy-created 

Status 

ok,  invalid__transaotioi^baadla 
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PRCXDEDURE 


serpentlnit 


Descrifron  T!ie  procedure  performs  necessary  initialization  of  the 

interface  layer. 


Syntax  ••rp«n^_inxts  < 

/*  mailbox  :  In  atelng  */ 
/*  111  £lla  :  la  string  *f 

)/ 


Parameters  mailbox  MAIL_BOX  constant  defined  in  SADDLE  generated 

include  file. 

ill^flla  ILLJPiLE  ctm^art  defined  in  SADDLE  generated 

~  induftefile. 


Status  ok,  oafe|^o£|jaamory,  n'oll_jiiallbox_nama, 

null_ill_£lla_naaaai,  systam^oparatlott  fallad 
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PROCEDURE 


setpent_cleanu  p 

C^SCraPTIOM 

The  procedure  performs  necessary  cleanup  of  the 

Interface  layer. 

Syntax 

Parameters 

None. 

Status 

ok 
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Procedure 


stert  recording 


Description  The  stert^recording  procedure  enables  recording.  Once 
start^seoordxng  has  been  called,  all  transactions  and  associated 
data  wMI  be  sav^  out  to  the  specified  file  until  the  stop_s«cording 
pracechjiB  is  1nv(ri«ed.  ^ 


Syntax  voxd  S'tart^recording  ( 

/*  string  */ 

/*  mmmmmqmimii  strixig  */ 

); 

Parameters  fiie^nans  Rte  to  wNch  to  M^tte  recording. 

assssge  RecoitBng  description. 

Status  ok,  io_£ailnre>  s3je»Sidhr^ocordiaq 
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Function 


startjransaction 

D^CmPTlON 

7118  stmrt_trattMctlon  function  is  used  to  define  the  start  of  a 
series  of  shared  data  modifications. 

Syntax 

txjuEiMe!fci.on_typ«  «bect_jtransacta.on  ( )  ; 

Parameters 

None. 

Returns 

A  urficpe  transaction  id 

Status 

ok,  out_o£ jummOKjf,  ov«r£low 
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Procedure 


stop_recording 

DESCRlPnON 

The  atop^roeording  procedure  causes  the  current  recording  to  be 
stopped  ~ 

SYNTAX 

void  a'top_r«eozdin9  ( ) ; 

Parameters 

None. 

Status  ok,  i.o__£ailux«,  invalxdyproc*as_,r*cord 

I 
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4.  Ada  Language  Application  Development 

This  part  inciudes  two  sections: 

»  How  to  Develop  af)  Application  in  Ada:  A  step  by  step  specification  of  the  tasks 
involved  in  dev^c^ng  a  Serpent  application  in  the  Ada  programming  language. 

•  Serpent  Ad%  1^^  Interface  Reference:  A  detailed  description  of  the 
types,  constants  and  routines  available  for  developing  Serpent  applications  in 
the  Ada  progrEvnming  language. 

4.1;  How  to  Develop  an  Application  in  Ada 

The  main  tasks  fW'  developing  an  appScation  for  Serpent  require  that  you  define  the  shared 
data,  add  intormattori  to  s^red  data,  and  retrieve  information  from  shared  data.  There  are 
also  two  adcfidortol  tasks  ^ich  may  applied:  recording  and  checking  status.  Each  of  these 
tasks  is  descrtoed  in  the  sute^ions  that  toitow. 

4.1 .1 .  Task  1 :  Defining  the  Shared  Data 

Defining  shared  data  inw^ves  two  steps: 

1 .  Create  the  shared  data  definition  file. 

2.  Run  the  created  file  through  the  SADDLE  proces»>r. 

The  following  is  a  brief  description  of  each  of  these  two  steps.  The  SEI  Serpent  SADDLE 
User’s  Guide  contains  a  more  con^lete  description  of  both  these  steps. 

Step  1:  Create  the  shared  data  defftddon  We  l^  shared  data  definition  file  defines  the 
type  and  structure  of  application  infbrma;S(»}  that  may  be  maintained  the  Serpent  shared 
database.  The  shared  data  definition  is  de^ed  in  an  extemaJ  ASCIi  Hie  in  SADDLE. 

Figure  4-1  is  a  example  of  a  shared  data  definition  file  tor  die  sonsor  site  status  application. 
The  content  of  the  shared  data  definition  file  is  independent  of  the  impfemer^tion  language 
used. 

The  file  shown  in  Rgure  4-1  contains  definitions  tor  the  data  shared  between  toe  application 
and  the  dialogue  for  the  sensor  site  status  application.  The  three  records  define  the  type 
and  structure  of  the  sensor,  correlation  center,  and  communication  line  application  ot^ects. 
Note  that  these  records  only  contain  information  to  define  the  actual  objects;  they  do  not 
specify  how  the  information  is  presented  to  the  end  user. 

Stop  2:  Run  the  created  file  through  the  SADDLE  processor.  Once  the  shared  data  has 
been  defined,  you  can  run  the  file  through  the  SADDLE  processor  to  generate sto  Ada  pack¬ 
age  specification  containing  Ada  type  specifications  correspondir^  to  tiie  defined  shared 
data  stmctures.  This  package  may  then  be  "withed”  in  your  Ada  application  in  order  to 
declare  local  variables  of  the  shared  data  types.  This  allows  you  to  directly  manipulate 
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••nsor_si.'ttt__statua : shaxad  data 

■asaos:  raeord:: 

sita^jBbbr :  atxing [3] ; 
atatua : iatagar; 
axta : atxing [50] ; 
laat^maaaaga:  atxing [8]; 
x£o : atxing [ 50} ; 
atxo :  atxiitg[8}  t 
xacoxd; 

eoxxalation^cantax ixaeord:  : : 
naaw;  atxing  [  3  ]  ; 
atatua:  intagax; 

and  xaeoxd; 

eonwiwn  icatiottj__lina ;  xaeoxd 
fxoa^aanaox :  id  of  aanaox; 
to_cc:id  of  coxxalation^jsaxitax; 
atxo : atxing [ 8 ] ; 
atatua : intagax ; 

and  xaeoxd; 

and  ahaxad  data; 

Ffgure  4>1 :  A  shaiBd  data  datflnttkm  fiJe 

shared  data  structures  in  Acte.  The  Ada  package  specilication  generated  by  mnning  the 
shared  data  definition  fiie  shovm  in  Rgure4>1  through  die  SADDLE  processor  is  iiiustrated 
in  Rgure  4-2. 

In  Rgure  4-2,  the  first  two  lines  in  the  file  provide  visibility  to  various  setpent  types  that  are 
used  within  the  package  specification.  This  is  followed  the  start  of  the 
sanaox_sita_statua  package  spedficadcm.  immediately  defiiiad  witivfi  the  package 
specification  are  two  well-known  constants:  leucLjsox  and  XLLjrxxx.  TTrese  constants 
are  used  in  Task  2  to  initialize  Serpent  The  three  record  definitions  correspcmd  to  the 
records  defined  within  the  shared  data  definition  file. 

4.1 .2.  Task  2:  Adding  information  to  the  Sfiared  Database. 

Oncre  you  have  defined  the  application  shared  data,  you  can  begin  to  develop  the  appti- 
cation.  The  code  segment  from  the  sensor  site  status  application  in  Rgure  4-3  illustrates 
the  basic  operations  for  adding  information  to  the  shared  database. 

Preliminary  Task  Steps 

In  preparation  for  the  task  of  adding  information,  you  need  to  complete  two  pretiminary 
steps; 

1 .  With  required  packaged  specifications. 

2.  Define  local  variables. 
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with  ««3:p*nt_typtt__d*£ini'ti.ons ; 
umm  — rp«aBt^typa_daf  initions ; 

paokag*  sttiiiBor_ait«i_»tatiic  is 

MXXL_BOX:  constant  string  :-"SSS_BOX"; 

XLL^rXU;  constant  string  iB^SSS-ill"; 

typo  sanaor^sdd  is  record 

sita^afabr :  string (1 . . 4 ) ; 

status:  intagar; 

site:  string  (1..51); 

string  (1.  .9)  ; 

r£o :  slicing  (1 . .  51)  ; 

atro:  string  (1 ..  9)  ; 

and  raeord; 

typa: corralation^cantar^sdd  is  record 
name :  string  (1 . .  4) ; 

status:  intagar; 

and  record; 

type  coaBnaioation^lina__sdd  is  record 
£raa_racosd;:  idjbypa;  —ZD  o£  sensor 
to_ce:  id^typa;  —ZD  of  corralation_cantar 

atro:  stciag:<l . « 9)  ; 

status:  intagar; 

and  record; 

and  sensor  site  status; 


Rgure  4-2:  Ada  language  header  die 

Step  PI:  With  required  pe^  •raged  specifications^  The  fkst  step  is  to  the  serpent 
package  specification  and  the  sensor_slte_stattis  pacteige  specification  generated  by  the 
SADDLE  processor.  The  serpent  package  spedfflda^  coigns  the  spedfication  of  the 
data  types  and  calls  that  you  will  need  to  interface  with  Serpent  The  sensor_slte_status 
package  specification  contains  the  shared  data  types  necessary  to  ctefine  local  instances  of 
the  shared  data  elements. 

Step  PZ:  Define  local  variables.  The  next  preliminary  step  is  to  define  the  required  local 
variables.  The  first  variable  defined  is  b’ansaction,  which  is  of  trnnsac^ionjtypo.  Thiis 
variable  maintains  the  handle  for  a  created  transaction.  The  next  variables  to  be  defined  are 
cno  and  o£t,  both  of  which  are  of  type  corrol«ti.on_cont«».  These  variables  store 
local  instances  of  the  data  that  is  going  to  be  shared  across  the  interfE^  with  the  Serpent 
system.  The  type  definition  for  the  corraiatxon_c«at«x  structure  was  automatically 
generated  by  the  SADDLE  processor  during  step  2  of  Task  1 . 
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with  ••rpwnt; 

««•  mmspnAr 

««nsor_sit«^statu« ; 
nmm  mmnmox^mLtm^jKtm.t'am : 

procwdnr*  main  is 

oft^nsM:  Cttostsnt  string  "OFT"; 
grssn^ststns:  constant  intagss  :*  0; 
ynlXoir^at&tittS :  constsait  intagss  :•  1; 
sad^a1»tins:  constant  istagas  2; 

transaction;  tsanaaetion^tj^ia; 
cniic_id,  o£t_^_^:  id_typa;^^^; 
cnc,  o£t;  cosral«tion_cantar; 

bagin  '' 

sarpant_init  (aasil^box:,  ilX^fila) ; 

cmc.naBa(l.  .cne^naaMMangth)  :>  aiic_naaia; 
erne . status  : «  graan_status ; 

oft .  naina  (1 . .  oift^^nana'  langth]^  ;«  oft^naan; 
oft . status  : ■  graan^status; 

transaction : astast^tsansaetion ; 

oft_id  :*  add_shasad^data( 
transaction, 

"corralation^cantar" , 

W  ff 

oft'addsass 

>; 

CBic_id  :*  add_shasad_data  ( 
transaction, 

"cosralation^cantas" , 

11  fl 

/ 

CBic'addrass 

); 

coaBiit_tsansaction  (transaction) ; 
sarpant_claanup ; 
satum; 
and  aain; 


Rgure  4-3:  Basic  calls  for  adding  information  to  the  shared  database 


The  two  variables  that  follow,  cac^id  and  oft_id,  store  the  ids  of  the  shared  data  in- 
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stances  created  in  shared  data.  It  is  necessary  for  the  application  to  maintain  this  infor¬ 
mation,  since  it  is  the  only  way  to  correlate  end-user  updates  with  local  application  infor- 
mafim  wf^  mid^jle  instances  of  a  single  shared  data  element  are  used. 

M^h  Task  Steps 

The  main  task  of  adding  information  to  the  shared  database  involves  five  distinct  coding 
steps: 

1.  Initialize  Serpent. 

2.  a  transaction. 

3.  Add  shared  data  to4»  interface. 

4.  Commit  the  trareactfoa 

5.  Clean  up^ 

Step  1:  tnWattiBe  Setpent  Once  the  appnc^riate  variables  have  been  declared  it  is  possible 
to  begin  describing  the  fogic.  The  first  st^  is  to  initialize  the  Serpent  system  using  the 
a«zpent_ixxi.t  call  and  passir^  the mxx^BOX  and  ZLL^rzuE  constants  generated  by  the 
SADDLE  processor  dunng  st^  2  of  ta^1. 

Step  2:  Start  a  transacOon.  Before  information  can  be  added  to  the  shared  database  it  is 
necessary  to  start  a  transaction.  All  additions  or  modifications  to  the  shared  database  must 
be  performed  as  part  of  a  transaction. 

Step  3:  Add  InformaOoa  to  ahm»d  datadj^  Once  a  transaction  has  been  started, 
you  can  begin  to  add  inforrhsdxm  fo  the  shared  database  as  part  of  this  transaction. 

Step  4:  Commit  the  tnnsaction.  T?te  actual  Grange  to  shared  data  does  not  occur  until 
the  transaction  is  committed.  Up  to  this  point  it  is  also  possible  to  roH  back  the  transaction 
so  that  none  of  the  changes  to  shared  data  occur. 

Step  5;  Clean  up.  The  s«rp«nt_jol«aa^  routine  rrust  be  invoked  before  exiting  the 
application.  It  is  important  that  you  complete  this  step,  to  release  ait  sdiocated  system 
resources. 

4.1.3.  Task  3:  Retrieving  Information  from  the  Shared  Database 

Once  application  data  exists  in  the  shared  database  it  may  be  fxesented  to  the  erfo-user 
using  one  or  more  of  the  available  technologies.  The  end-user  may  in  turn  make  modifica¬ 
tions  to  this  data.  These  modifications  are  sent  back  to  the  application  to  be  updated  in  ttie 
application's  locai  database.  It  is  therefore  necessary  for  the  application  to  r^rieve  infor¬ 
mation  back  from  the  shared  database. 

The  Serpent  interface  provides  both  synchronous  and  asynchronous  calls  for  getting  infor¬ 
mation  back  from  the  shared  database.  The  following  code  segnrent  from  the  sensor  site 
status  application  in  Rgure  4-4  illustrates  the  basic  calls  required  to  synchronously  retrieve 
data  from  the  interfoce. 
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proc«dnr«  gwb^usttr^updat**  xm 


COttS^aiVtS.: 

o£t;_naiiM:  coBS^taB-b  string  ”OFT"; 
grssn^ststusi  ooastsnt  Intsgsr  :>  0; 
ysllow^stS'bQs:  oonsbsnt  intsgsr  :>  1; 
rsd_^ststus:  csonstsnt  intsgsr  2; 

Hsitsinsd  'data . 

tmaaet  ion :  tranasetion^Jtyps ; 
id:  id^yps?  t 

sharsd  data  siaomat :  hash  slaawnt ; 


bsgin 

—  Rstrisvs  information  fron  sharsd  databaas. 
transaction  gat^ranaaction; 
id  :■  gst^£irat__ehangsd_slamamt{tranaaotion) ; 
whils  id  /«  niill_id  loop 

shar sd^data_slamaBt  :  «*  gst^froa^haaditabls  ( id_t abls ,  id) ; 
incorporats_changas ( 
transaction , 
id, 

sharsd  data  slsmsnt'  addrsaa 
id  :  ■  gat_nsxt_changsd_jslaB«nt  (transactiMi)  ; 


and  loop; 

purgs^transaction (transaction) ; 


rstcm; 

and  gst_uasr_jQpdatss; 

Rgure  4-4:  Basic  calls  required  to  retrieve  data  synchronously 
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Task  Steps 

The  task  of  (etrfewing  information  from  the  shared  database  involves  three  distinct  coding 


1.  Get  a  transac^on; 

2.  Update  locaf  ctatabase. 

3.  Purge  transadtloa 

Step  1:  Q(BtMpam8actlon.  The  first  step  in  retrieving  information  from  the  shared  data 
base  is  to  a  bansaction.  The  getjtransaction  routine  waits  until  a  transaction  is 
aireiabia  returns  a  handle  for  this  transaction.  To  poll  for  a  new  transaction 

asynchronously,  it  is  pOSSfisie  to  ca8  the  g«t_transaction_no_ifmi.t  routine,  which  will 
return  not_availja>le  if  rio  transaction  is  available. 

Step  2:  Updatm  xtei^base.  Transactions  can  be  thought  of  logically  as  a  list  of 
changed  ei^^tts.  The  next  call,  gttt;;;jeicst_ehanged_*l«iii^  returns  the  id  of  the 
first  changed  element  on  the  list  This  id  can  then  be  used  to  access  several  types  of  infor¬ 
mation  about  the  shared  data  eiement 

The  appiication  must  msdntain  a  correlation  between  the  shared  data  ids  and  the  actual  data 
items  to  incorporate  chai^i^  succ  into  its  existing  local  data.  For  the  purposes  of 
this  example,  it  is  assumed  that  this  database  is  irsfrrtairted  as  a  hashtable  indexed  by  the 
shared  data  eiement  id.  The  purpc^e  ol  the  wMie  loop  then  is  to  incorporate  all  of  the 
changes  into  this  local  database  or  t«^itePie.  A  pcrinterto  the  shared  data  element  to  be 
updated  is  retrieved  from  the  hashtsdbie  using  the  g«tn£roaajha«btable  routine  and  pass¬ 
ing  id  as  an  index  into  the  hashtablei  iBooa:pormte_chaAges  call  then  makes  the 
updates  to  the  local  description  of  the  ^»fed  data  elements  and  whatever  changes  were 
made  by  the  dialogue. 

The  last  call  within  the  loop  gets  the  next  changed  elernent  from  the  transaction.  The  loop 
repeats  until  a  tmil_i.d  is  returned. 

Step  3:  Purge  transaction.  After  the  loop  ends  ttte  transactton  can  be  pwged  safely.  It  is 
your  responsibility  to  ensure  that  transactions  are  pwged,  ^nce  this  call  releases  resources 
that  othenivise  could  run  out. 

4.2.  Recording  Shared  Database  Transactions 

There  are  two  major  tasks  that  need  to  be  perfonned  when  using  the  record/playback  fea^ 
ture  of  Serpent  for  testing  the  application  or  user  interface: 

1 .  Recording  shared  database  bansactions. 

2.  Testing  the  application  or  user  interface. 

Since  the  steps  involved  in  the  second  task  can  be  perfomned  independent  of  the  implemen- 
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tation  language  they  are  described  later  in  the  Application  and  Diaiogue  Testing  part  of  this 
guide. 

BelCHe  te^f^  the  application  or  the  dialogue  however,  you  must  first  record  the  transactions 
you  wottid  like  to  use  in  testing.  Rgure  4-5  illustrates  the  basic  operations  for  recording 
hansactions. 

teansactlon:  txaaMcbxon^<byp«; 
hmg±n 

—  Start  raeordiag. 

st«rt_xaoordiag ("xacordittg^v  "taat  data :  5.7.3"}; 

—  Sand  taat  data. 

tranaaetlon  :«  atart^trattaaetlon; 

coouLt^txattaafietion  (tranaaetlon) ; 
tranaaetlon  :«  atart  Jbranaact ion; 

oaa>lt_jtranaactlon  (tranaaetlon)  } 
tranaaetlon  :«  atart^jtranaaetloa:; 

oaanilt_tranaaotlon  (tranaaetlon)  ; 

--  Stop  raeordlng. 
a  top__raoordlng ; 

and  aaln; 

Rgure  4-5:  Recording  transactions 
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Task  Steps 

There  am  th(^  distinct  coding  steps  involved  in  recording  shared  database  transactions: 

1.  ^rt  racorcSng; 

2.  Send  transaetionSi 

3.  Stop  mcordin^^ 

Step  1:  Start  recording.  The  first  step  is  to  begin  recording  by  calling  the 
•tmrtjEecordin^rfOutine  specifying  both  the  name  of  the  file  in  which  to  save  the  record¬ 
ing  and  a  mei^c^  to  help  identify  the  file. 

Step  2:  Send  transacttone.  Afi^  tiie  call  is  made  you  may  start  sending  transactions 
across  the  interface.  Vdu  may  send  any  number  of  transactions  containing  any  type  or 
amount  of  data. 

Step  3:  Stop  reeordingi  Once  start jr*cordi.ng  has  been  called,  all  transactions  and 
associated  data  will  be  saved  exit  to  the  specified  file  until  the  stop_racording  routine  is 
invoked. 

4.2.1.  Checking  Status 

Each  routine  in  Sei|^f»lts  status  on  exit.  It  is  good  software  engineering  practice  to 
check  this  status  after  every  call  to  make  sim  that  Vne  routine  has  executed  coirectly,  and 
provide  appropriate  recovery  actions  if  it  has  rwt  4-6  shows  the  operations  that  Ser¬ 

pent  provides  for  examinktg  the  status. 

transaction  start  transaction; 
if  g«t_status  /«  ok  than 

print_statns("bad  states  frosK  start  transaction"}; 
ratnm; 
and  if; 

Rgure  4-6:  Operations  for  exatrfining  the  status 

The  first  of  these  status  calls  is  the  gat_status,  wNch  r^ms  an  enummatton  of  status 
codes.  Valid  status  that  each  routine  in  Sorpent  may  mtum  aA  defined  in  ^  reference 
sections  of  this  developer’s  guide. 

The  print_status  routine  prints  out  a  user-defined  error  message  and  the  current  status. 
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4.3.  Serpent  Ada  Language  Interface 

4.34.  Typee  and  Cwistants 

This^^  contains  the  type  and  constant  definitions  that  are  used  in  the  Ada  language 

bito'face  to  the  Serpent  sp^tn.  The  following  is  a  list  and  short  description  of  each  of  these 
^^s  and  constants.  A  mote  complete  description  immediately  follows: 

lype/Constant  OeleHption 

buffer  to  define  the  structure  of  a  shared  data  buffer 

chmgejbyp*  defines  the  type  of  modification  made  for  an  element 

idjbype  used  to  uitiqueiy  identify  shared  data  elements 

nuli_id  defines  the  null  value  toe  id_type 

••rp«nt_dat&^byp«r 

an  enumeration  of  defir^  S^pent  data  types 

transact loojbype 

used  to  define  trsfftsactton  handles 

undaflnad  valuas 

Constants  corresponding  to  undefined  values  for  all  supported  types 
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Type 


DESCRtPHOM 


Definition 


The  buffME  type  is  used  to  define  the  structure  of  a  buffer  within 
shared  dalsi  ^ 


tjipm  bu££«r  ±m  x*cord  { 
length  :  xn^ng^; 
bod^  ::  •ysten.address; 
•nd  reteoard; 


Components  length 
body 


Length  of  the  buffer  in  bytes. 
Address  dthe  actual  buffer  data. 


TYPE 


OE^mPTiON  The  change_type  defines  the  type  of  modification  made  for  an  eiement. 


DERNmON  chang«__typtt  im  (no_ch«ng«,  crMt«,  modify, 

zmaovm,  gmt) ; 


no_eh4tnge; 

r«niov« 

OTMta 

iaodi£y 

xmmyrm 

gmt 


COMPONENTS 


Notohanged  or  invalid  change. 

Remove  existing  shared  data  instance. 
Newty  created  shared  data  instance. 
Modified  existing  stored  data  instance. 
Renrave  exisUr^  shes^jl  data  instance. 

Get  vafete  for  existing  shared  data  instance. 


62 


CMU/SEI-69-UG-6 


TYPE 


Description  The  id  type  is  used  to  uniquely  identify  shared  data  elements. 


Definition  int; 
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Constant 


OESCffiPTtON  Tile  nulljd  constant  defines  the  null  value  for  the  id_type.  This  con¬ 
stant  can  be  used  to  test  for  null  id  values. 


Type 


seipent_clata_types 


DESGRiPnoN  The  serpent  data  types  type  is  an  enumeration  of  the  defined  Serpent 
datatypes. 


Definition  ••rpttnt._dsfca__byp«s  i*  ( 

Mrp«nt.__in'b«g«;^ 

•expeotr^rijag^ 
SAspttBt^jrttGord, 

•expeat^xd, 

Mxpent  bu££«x 

► 


I 


I 


r 
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transactfon^type 


OESCRiPTOit  Vanables  of  trans^ionjtype  are  used  to  define  transactions. 


DERNITION  'typ*  teaasmcbioi^-bypa  la  privata; 
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undefined  values 


Descripticx^  The  following  constants  correspond  to  undefined  values  for  ail  types 
supported  by  Serpent  These  constants  can  be  used  to  test  for 
ndeSned  shared  data  components.  When  checking  for  an  undefined 
record  is  best  to  check  the  buffer  length  failed  for 

QHXSrZllED  BOITSSt  LSNGTB. 


4.3.2.  Routines 

This  subsecti<»i  (tescribes  the  routines  that  make  up  the  C  language  interface  to  Serpent. 
These  routines  fall  into  the  following  categories: 

« tnitialization/ciearutp 

•  serpentjnit 

•  serpent_cieamip 

«  Tmnsactksi  |»ocessin 

«  staurtJransaction 

•  commitjtransadion 

•  rollbacMiiiiJsacKcm 

•  get_fiRansMWlion 

•  grt_bansaction_noj«ait 

•  purge_transaction 

• 

•  Sending  and  retrieving  daM 

•  add.sharedLdaia 

•  put_shared_data  * 

•  remove_sharedjdata 

•  get_first_changed_rt6rnarjt 

•  get_next_changed_element 

•  get_shared_data 

•  incorporate.changes 

•  create_changed_componentJi8t 

•  destroy_changed_component_8st 

•  get_change_type 

•  get_element_name 

•  get_shared_data_type 

• 

•  Record/playback 

•  start_recording 

•  stop_fecording 

•  Checking  Status 

•  get_status 

•  print_status 
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Function 


add  shared  data 


DESCRiFTOd  The  add_^shar«d_data  routine  creates  an  instances  for  the  specified 
shared  £tta  element  and  returns  a  unique  ID.  The  shared  data  in¬ 
stanced  may  or  may  not  be  initialized. 


Syntax  ^uaefexon  «dd_shac«d_da‘ta  ( 

'transaction  :  in  tsansaction_typa; 
sT  Mnanr_^n iina .  ceagponant_naiiia  :  in  string; 
data  :  in  systsm . address 
)  retttra:  id^jtype ; 


transaction 

The  transactor!  for  which  this  of»Fa&)n  is  defined. 

The  name  of  the  shared  data  element 

The  name  of  a  speclic  ctHnponent  to  be  initialized  with  the  data  or  null  if 
the  data  correspondsio  the  mtire  element. 

data  or  null  pointer  if  norMnitialized. 


returns 

The  ID  of  the  newly  created  shared  data  instance. 


Status 

ok,  ont_o£_aMniory,  null__alsaMnt_naias,  overflow) 


PARAMETERS 

al«Bant_naias 

coaponant_nsiBS 

data 
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Routine 


coinfnit_transaction 


Description  The  eaaBitjkx«n«aeti.on  procedure  is  used  to  commit  a  transaction 
to  the  shared^atabase. 


Syntax  proeed»r«  coani.'t_;bxMisac'tlon  ( 

:  torana»etion  :  la  'txansactlon  typa 


Parameters  teansaotlon  Existing  transaction  ID. 


Status  ok,  oat^fj wor y | 


CMU/SEI-89-UG-6 


Function 

cr^te_changed_componentJist 

DescRiPTlON 

The  crM.'b«^changad_caapon«nt__list  function  accepts  an  in¬ 
stance  id  as^  parameter  and  creates  a  list  of  changed  component 
names. 

Syntax 

fuxkcbi.on  cr«a^*^^tang*d_coapon«nt_lxs't  ( 
xd  :  xn  xd__typ« 

)  ratnrn  XtZST:; 

Parameters 

id  Existing  data  instance  id 

Returns 

The  Sst  ct^nged  CKxnponent  names  associated  with  a  data  instance, 
or  HOLi.  if  twnei 

Status 

ok,  xnvmlxd_xd,  o«t._jo£_aiaaiory,  olasaBiKt^notja^rocord 
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PROCEDURE 


destroy_changed_componentJist 

OESCraPTlOM 

Tho  daa'troy  ohangad  eonponan't  list  procedure  releases 
associated  with  a  changed  component  list. 

Syntax 

procMidiira  dsstroy^ehangad_coiBponaat_llst  ( 

^laogad  coaoponaat  list  :  In  LIST 

Parameters 

chsngsMl  eoaaponant  list 

^  to  be  destroyed. 

Status 

ok 
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g^|chang&_type 


DEscRipmcm 


Syntax 


Pie  9«t_^chaag*_;type  function  accepts  an  instance  id  as  a  parameter 
and  retu^  the  associated  change  type. 


itanetion  g«1:_jdbuige_typ«  ( 
Id  t  in  id_;byp* 

}  return  chnngn^teype; 


Parameters  id 


Existing  shared  data  ID 


RETURNS 


Status 


Element  name  assodated  v)rithtt»  shared  data  instance  ID. 


ok^  in'vmlid_dhaakg»_;kyp*>  invalid^jbranaactioa^handle, 
invalid  id 
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FUNCTION 

get_element_name 

DESCmPTKM 

The  function  accepts  an  instance  id  as  a 

parameterand  reim^  the  associated  element  name. 

Syntax 

xd'  '  t:  itt  id_typ«  ■  ■ 
f  rmturtL  efcring; 

Parameters 

id  Existing  shared  data  ID. 

Returns 

Element  name  associated  with  the  shared  data  instance  ID 

Status 

ok,  invalid^^id 
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Function 


ge^rs 

ifxlianged_element 

Description 

The  g«'b__£xrst_cha&gttd_*laiii*nt  function  is  used  to  get  the  id  of 
the  first  clianged'element  orTa  transaction  list. 

Syntax 

function  g«t__firat_chnng«d_*l«innnt  ( 
trniisaetion  :  in  tranaaction_typ« 

)  ratuxn  id_bypa; 

Parameters 

tranaaetion  Existing  transaction  iD 

Returns 

The  handle  of  the  change  etenr»ni  ‘ 

♦ 

Status 

ok,  invalid_tra»aact ion^handla ,  out__o£_jaanory 
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Function 


get_next_changed_element 

Description 

Tlie  g«t_n*xt._jdhang«d^*l«a«nt  function  is  used  to  get  the  id  of  the 
next  changed  elairont  oiT a  transaction  list  or  return  null_i.d  if  the 
transaction  fist  is  empty. 

Syntax 

fnnebiox^  ( 

'branMicfci.on  :  x&  t:x«nsac^ion_byp« 

)  ra^urn 

Parameters 

txmsaefciion  Existing  transaction  ID 

Returns 

The  handle  of  the  next  changed  elenn»it 

Status 

ok,  invalid  ‘transaction  kandla,  out  of  aMoocy 
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Function 


get_shared_data 


DESCRIPTION  The  g«t__ahax*d_dat:«  function  allocates  process  memory,  copies 
shared  d^into  process  memory  and  returns  a  pointer  to  the  data. 

Warning:  Record  componerrts  may  not  have  been  specified  and,  therefore,  would 

•  not  contain  valid  data 

Syntax  fisneti-on  ( 

‘transaction  :  iA  transact ion_typa 
id  :  in  id^typa 
coa|p<mant_nains  :  in  string 
)  ratum  systam. address; 

PARAMETERS  transaction  Transaction  in  vy^ch  to  find  the  Shared  data  id. 

*•  ♦ 

id  Existing  sha^  data  id. 

coiiiponant_naBaa  Nana  of  component  for  which  to  retrieve  data,  or 
~  entire  element  if  NULL. 

returns  a  pointer  to  changed  data 

Status  ok,  invalid_id,  ont_^o£_8Maory,  iucoaplata__racord 
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Function 


get_sharecl_data_type 


DESCniFnON 

llie  9«t_ahar«d^  function  is  used  to  get  the  type  associ¬ 

ated  withli  shareddata  ^ment. 

Syntax 

funotion  gat._ah»rad^dnta_typa  ( 

alammt^naiM,  coiipon«nt_naxaa  :  In  abring 
)  rabum  sarpanb^dabajtypas ; 

Parameters 

•laaaab_aaiaa  The  name  of  the  shared  data  element 
eoapeaanbjttaioa  The  name  of  the  shared  data  component,  or  NULL 

Returns 

The  type  of  the  Glared  data  element  or  record  component. 

ok,  null  mlmamiot 


Function 


get_status 

DESCRIPTION 

The  function  returns  the  current  system  status. 

Syntax 

ftmcrbion  return  statu«__codas; 

Parameters 

None. 

Returns 

The  currant  status. 

Status 

Monesv:' * 
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Function 


get_fransacfion 

DESCRIPTION  ; 

The  gmt  toanMctlon  function  is  used  to  synchronously  retrieve  the 
id  for  theTneid  completed  transaction. 

Syntax 

faacfcloa  gat^'trasM.c'tion  raturn  transaction_typ« ; 

Parameters 

None. 

Returns 

The  transaction  ID  for  a  completed  transaction 

Status 

ok,  •ys't«a^'^«3:a;fci«n_£ai.lad 
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► 

Function 


get_transaction_no__walt 


Description  The  g«t_traas«ction  function  is  used  to  asynchronously  retrieve  the 
id  for  the*next  completed  transaction. 


[BSYNTAX  £aset.3Lon  g«t_transactlon__nojirait  xatum 

tranaact  i.on__typ«  ; 


PARAMETERS  None; 


Returns  The  transaction  ID  for  a  complied  transaction 


Status  ok,  syatam^oparatlon^faiJLad,  not^availabla 
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Procedure 


incorporate_changes 


Status  ok,  in'vmiid  id 
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Procedure 


print_status 

DBSCRIPT)C3M 

The  prxnt^status  procedure  prints  out  a  user  defined  error  message 
and  the  cuR^t  status. 

Syntax 

proottdur*  prijit:_jrbatus  ( 

•aexox  mag  :  in  mtxing 

"  ); 

Parameters 

•rxoxjnag  User-defined  error  message. 

Status 

Hon* 
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PRCXDEDURE 


purge. 

transaction 

OESCRiPTION 

The  purge  transac&)n  procedure  is  used  to  purge  a  received  transaction 
once  the  contents  of  the  transaction  have  been  examined  and  acted 
upon. 

Syntax 

proe*dace  purge.'traiiMetion  ( 

tranaaetion  :  in  Cxanaactlon  typa 

); 

Parameters 

'traasaefedbon  Existing  transaction  ID. 

Status 

ok,  invmXi^id,  xllagal.raeelvar 
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Routine 


put_shared_data 


Description  The  pnt__shax«djdata  call  is  used  to  put  information  into  shared  data. 


Syntax  ]^eoc«dar«  pttfc^shared^da'ba ( 

tram  aact ion.  :  xxx  transaction_typa; 
id  i  in  id^jjpa; 
alaaian-b_nama  :  in  atring; 
cooqaonantjBaiaa:  t  in  string; 
data;  ;  in  systSBi.addrass 

); 


• 

Parameters 

transaction 

Tt»  trans£tttion  to  which  the  shared  data  should  be 
puti  Si- ^ 

id 

Shared  data  ID. 

al€BMnt_naiaa 

The  name  of  the  shared  data  element. 

eoa)ponant_nan 

ft  Rsmrie  of  the  shared  data  component. 

• 

data 

ShsBBddata. 

• 

Status 

ok,  unda£inad_^sharad_data__typa,  null._jalaaiant_naina, 
in^alid^id 

• 

• 
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PRCXJEDURE 


remove. 

.sharecl_data 

DESC^PnOlSi 

Tile  x«Bov«i_aha£ed_da^a  procedure  is  used  to  remove  a  specified 
shared  data  instance  fiom  the  shared  database. 

Syntax 

pxooednre  r«iiiov«^ah«x«d__data  ( 

1:ra&aaetioa  :  in  txansaction__typ«; 

•  1  amant.,waina  :  in  string; 
id  :  in  id  type 

); 

Parameters 

transection  Transaction  from  which  to  remove  the  shared  data 

element. 

elsBMntjoasMs  Name  of  element  to  be  removed, 

id  .  Existing  shared  data  ID. 

Status 

ok,  oat_of_Biaiaory,  nulJLjaleaiant__naais,  iavelid_id 
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rollback  transaction 


DESCRIPTION 


Syntax 


The  rollback__tsan«action  procedure  is  used  to  abort  a  given 
transaction  iEuid  deiete  the  associated  transaction  buffer. 


prooadura  ro 11 bank^transactien ( 
transaction  ;  in  transaction_typa 


PARAMETERS  transaction  Existing  transaction  ID. 


Returns  A  handle  to  a  newly-created  element 


STATUS 


ok,  invalid_tsa&saetion^handl« 
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Procedure 


DESCRiPTlON  The  sttxpAnt^xnxt  procedure  performs  necessary  initiaiization  of  the 
Pntarface  layerr 


SYIMTAX  pcooadore  STput^init  (mailbox,  in 


Parameters  mailbox  MA1L_BOX  constant  defined  in  SADDLE  generated 

include  file. 

ILL.FILE  constant  defined  in  SADDLE  gene'^ted 
include  file. 


Status  ok,  outja£jBOBioz3T>^||^;i^^^  l  zralljBai.lb03ejaaiB0, 

aiill_^i.ll__£Ha__naBMi;^  ayakaBnoparaki.on_fai.lad 
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Prcxjedure 


serpent_cleanup 

DESCRIPTION 

The  mmrpmat^Glmmmip  procedure  performs  necessary  cleanup  of  the 
interface  %ei^ 

Syntax 

prooedur*  ••3^«at._cl«anup; 

b  Parameters  None. 


Status  ok 


► 


I 


I 
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Procedure 


stat1_recording 


DESCfUFFiON 


Syntax 


Hfsl  ctart^^TMording  procedure  enables  recording.  Once 
start_r«oa«ding  has  been  called,  all  transactions  and  associated 
data  will  be  sawed  (Hit  to  the  specified  file  until  the  •top_rttcording 
procedure  Is  invoked  ~ 


procedure  ft'barti__rfteord±ng  ( 

txansftctixon  :  iA:  'txansac'kion_byp«i ; 
file  naoM  :  xs  eteong 


Parameters 


aMSsag* 


Rle  to  wwhich  to  write  recording. 
Recording  descripdon. 


Status 


ok,  io^failura,  alxeadji^rocording 
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Function 


start  transaction 


STATUS 


ok,  o«k^of_aiaBMry/  ov«fiflo«r 
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V-H. 


PROCEDURE 


stop_recoroling 

Descfhption 

Itts  stopjE«cordxng  procedure  causes  the  current  recording  to  be 
stopped.  ~~ 

Syntax 

prooedore  stop_r«eording; 

Parameters 

None. 

Status 

ok,  ix>^£ai.lux«,  invalid jproeMs^racord 
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5.  Application  and  Dialogue  Testing 


5*t .  Ptayback/Record 

^Fhere  are  two  msyor  ia^  that  need  to  be  performed  when  using  the  record/playback  fea¬ 
ture  of  Serpent  for  teeSng  the  application  or  user  interface: 

1 .  Recordif^  sf^soed  database  transactions. 

2.  Testkig  the  application  or  t^r  interface. 

The  st^  involved  in  the  spedffcatfon  of  the  first  task  are  dependent  on  the  language  in 
which  the  application  was  developed;  therefore  a  description  of  the  steps  involved  in  record¬ 
ing  shared  dat^jase  t^sactions  is  ihcitKied  in  both  the  C  language  and  Ada  language  ap¬ 
plication  deveiofjmsnt  parte  of  this  guides 

5.1.1.  Testing  the  Apfdlcation 

Once  you  have  made  a  recr^tfing  it  is  possible  to  use  that  recording  to  test  either  the  appli¬ 
cation  or  the  dialogue.  This  is  accomplished  by  using  the  recording  to  simulate  the  user 
interface  (when  testbig  ttte  af^lication)  or  the  application  (when  testing  the  dialogue).  In 
order  to  test  the  Senso:^  She  Status  application  (sss)i^  ior  example,  you  would  njn  the  app- 
test  command  provided  with  Serpent  specif|^ng  lx>th  the  application  to  be  tested  and  the 
name  of  the  file  containing  the  recorded  test  data,  as  iiki^rated  in  Figure  5-1 . 

%  app-tevb  «•«  xeoordiag 
Playing  back  jooinkal  £ila;  recording 
Massage:  regression  best:  dali:a,  S.7.3 
Playback  coiapleted  snccess£ally 

%  _ 

Figure  5-1:  Testing  the  Applicadai 

The  app-test  command  will  then  simulate  the  diaiogio  mans^r.  This  technk)ue  allows  the 
application  developer  to  test  the  application  vddxxh  the  ciHak^ue  manager  The  application 
must  be  tested  in  the  same  directory  as  the  recording  was  madeu 


5.1 .2.  T^ing  the  Dialogue 

The  same  recording  can  also  be  used  to  test  the  user  interface.  In  order  to  test  tt^  Sensor 
Site  Status  dialogue  (sss.dlg),  for  example,  you  would  run  the  dialogue-test  command  pro¬ 
vided  with  Serpent  specifying  both  the  name  of  the  dialogue  to  be  tested  and  the  name  of 
the  file  containing  the  recorded  test  data,  as  illustrated  in  Rgure  5-2. 

The  dm-test  command  will  then  simulate  the  application.  This  technkjue  aHows  the  dialogue 
specifier  to  test  the  user  interface  without  the  actual  application;^^  important 

that  the  dialogue  be  tested  in  the  same  directory  as  the  recording  was  made. 


%  dn-tMt;  ««s.dlg  rttoording 

jouraal  £il« :  r*cordixig 
Ummmmffmt  ximgsmmmi.Qn  tttst  data,  5.7.3 
Bligfback  oonplatad  auccassfuUy 

%  _ 

5>2:  Testing  the  User  Interface 
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5.1.3.  Commands 

This  si^sectton  contains  definitions  of  some  commands  provided  with  Serpent  to  assist  in 
testbig  Sequent  applications  and  dialogues.  The  following  Is  a  list  and  short  description  of 
each  of  these  commamfs.  A  more  complete  description  immediately  follows: 

Command  Oeacilption 

app'tttat  used  to  test  an  existing  application  by  simulating  Serpent  execution 

to  test  an  existing  dialogue  by  simulating  the  application  program. 
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Command 


Desc^ptkdn  ITie  applicatjon-rtet  command  can  be  used  to  test  an  existing  applica¬ 
tion  by  simulating  SiKpent  execution.  The  application-test  command  re¬ 
quires  a  iBCoitfing  of  the  application  to  be  made  prior  to  testing.  The 
appUced^on  fmust  thm  be  te^d  in  the  same  directory  as  the  recording 
wasmade: 


DERNITiON  app-tesa  >^iplxeaEfcxoBt  fil( 


Parameters  applicwtiioa  The  name  of  the  application  being  tested.  The  ap¬ 
plication  is  assumed  to  be  in  the  working  directory. 

fileaaxM  The  name  the  ffle  comaining  the  recording  to  be 

l^ayedbadt. 
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Returns 


ok 

appMca&m  not  found 
piaybadc  file  not  found 
err»  during  playback 


Command 


didc^ue-test 


Descriptkm  The  dialogue^test  command  can  be  used  to  test  an  existing  diaiogue  by 
simulating  the  application  program.  The  dialogue-test  command  re¬ 
quires  a  record^  of  the  application  to  be  made  prior  to  testing.  The 
cHatogtie  tmjstthen  be  tested  in  the  same  directory  as  the  recording  was 
macte. 


DERNmON:|:>  ^  dialogue^Mt;:  dialogue  £i  lentne 


PARAMETERS  dialogue  The  name  of  the  dialogue  being  tested.  The  dia¬ 

logue  is  assumed  to  be  in  the  working  directory. 

filenaae  The  nmne  of  die  fite  containing  the  recording  to  be 

played  back. 


Returns  0  ok 

1  ctiak^e  not  found 

2  file  not  found 

3  error  during  j^e^baadc 


Appendix  A:  Glossary  of  Terms 


af^iiration  faycHT  those  components  of  a  software  system  that  implement  the  "core”  appli¬ 
cation  functionality  of  the  system. 

<fiaiogue  a  specification  of  the  presentation  of  application  infonnation  to,  and  in¬ 

teractions  with,  the  end-user. 

dialogue  layer  Serpent  layer  that  controls  the  dialogue  between  the  application  and 
the  end-user  of  the  application. 

(fialogue  managw  ^rpent  conr^nent  that  executes  the  dialogue. 

ID  unique  shared  instance  identifier. 

I/O  technologies  easting  hardware/software  systems  that  perfonn  some  level  of  general¬ 
ized  ii^raction  with  the  user. 

presentation  tayer  Serpertt  layer  concerned  with  low  level  interaction  with  the  user.  This 
lay^  consists  of  the  various  I/O  technologies. 

presentation  Independent  ^ 

independerrt  of  the  user  interface  of  the  system. 

shared  database  Application  and  technology  data  maintained  in  Serpent 

shared  data  definition 

a  deserfpfion  of  the  type  and  structure  of  data  that  can  be  placed  in  the 
shared  database. 

shared  data  element 

any  shared  cteta  structure  that  may  be  instantiated  at  run-time. 

shared  deta  Instance 

an  instance  of  a  tiered  data  etermnt. 


transaction 


user  Interface 


a  collection  of  ufxiatss  to  the  shared  database  that  is  logically  proc¬ 
essed  at  one  time. 

those  components  ofasoitware  system  Vnsi  sped^  the  presentation  of 
application  informaSon  to.  and  interactiortwito.  theandHiser. 
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